Hi,

Thank you @lbartoletti for submitting this.

I have a few points about the overall structure, as it is not rendering well. Please use one sentence per line, following the current style of the chapter. Also, please reduce the usage of the word "you."

Attached is a patch for this PR with my suggestions. Take a look and see if you agree or if you want to change anything else.

Just a note here: the author is a FreeBSD committer and can push this by himself to the doc repository.

Overall this looks a nice improvement. There are a couple of points that I think could use some clarification however:

1. xdg-desktop-portal reads the XDG_CURRENT_DESKTOP environment variable to determine which configuration file in the xdg-desktop-portal directory to use. For example, setting XDG_CURRENT_DESKTOP=sway is necessary to cause it to use the sway-portals.conf file in the example given.

2. Running dbus-update-activation-environment ... is necessary to ensure that the WAYLAND_DISPLAY (and perhaps XDG_CURRENT_DESKTOP) environment variables are set in the environment of the xdg-desktop-portal dbus service when it is started through dbus activation (e.g. when Firefox accesses the screen sharing dbus interface and xdg-desktop-portal is not yet running).

3. If there is no dbus session bus already running when dbus-update-activation-environment is run, dbus-update-activation-environment will automatically start one. However this is not necessarily desirable as the automatically started dbus session bus instance is not exposed through the DBUS_SESSION_BUS_ADDRESS environment variable and there is a risk of accidentally starting multiple session buses that are not aware of each other such that firefox does not connect to the session bus where xdg-desktop-portal is running.

   It would be more robust to explicitly start the dbus session bus before the Wayland compositor is started. Linux distros using systemd or alternatives like turnstile start exactly one dbus session bus per user that is shared across all login sessions.

   Since we do not currently have infrastructure to manage the dbus session bus in that way on FreeBSD, I think the most robust way to handle this is to set things up in a wrapper script that starts the Wayland compositor:

#!/bin/sh
export XDG_CURRENT_DESKTOP=sway
# Starts a session bus instance of dbus-daemon(1) and sets $DBUS_SESSION_BUS_ADDRESS
# in the environment before executing sway
exec dbus-run-session sway

And then in the running Wayland compositor inform the dbus session bus of the WAYLAND_DISPLAY variable set by the compositor:

dbus-update-activation-environment WAYLAND_DISPLAY